---
title: Référence de l'API Actions
sidebar:
  label: 'astro:actions'
i18nReady: true
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 6
---
import Since from '~/components/Since.astro';
import ReadMore from '~/components/ReadMore.astro';

<p>
<Since v="4.15.0" />
</p>

Les actions vous aident à créer un backend incluant la sûreté du typage que vous pouvez appeler à partir du code client et des formulaires HTML. Tous les utilitaires permettant de définir et d'appeler des actions sont exposés par le module `astro:actions`. Pour des exemples et des instructions d'utilisation, [consultez le guide Actions](/fr/guides/actions/).

## Importations depuis `astro:actions`

```js
import {
  ACTION_QUERY_PARAMS,
  ActionError,
  actions,
  defineAction,
  getActionContext,
  getActionPath,
  isActionError,
  isInputError,
 } from 'astro:actions';
```

### `defineAction()`

<p>

**Type :** <code>(\{ accept, input, handler \}) => <a href="#actionclient">ActionClient</a></code>
</p>

Un utilitaire permettant de définir de nouvelles actions dans le fichier `src/actions/index.ts`. Il accepte une fonction [`handler()`](#propriété-handler) contenant la logique du serveur à exécuter et une propriété facultative [`input`](#validateur-de-saisie-input) pour valider les paramètres d'entrée lors de l'exécution.

```ts title="src/actions/index.ts"
import { defineAction } from 'astro:actions';
import { z } from 'astro:schema';

export const server = {
  getGreeting: defineAction({
    input: z.object({
      name: z.string(),
    }),
    handler: async (input, context) => {
      return `Bonjour, ${input.name}!`
    }
  })
}
```

#### Propriété `handler()`

<p>

**Type :** <code>(input: TInputSchema, context: <a href="#actionapicontext">ActionAPIContext</a>) => TOutput | Promise\<TOutput\></code>
</p>

Une fonction requise contenant la logique du serveur à exécuter lorsque l'action est appelée. Les données renvoyées par `handler()` sont automatiquement sérialisées et envoyées à l'appelant.

Le gestionnaire (`handler()`) est appelé avec la saisie de l'utilisateur comme premier argument. Si un validateur [`input`](#validateur-de-saisie-input) est défini, la saisie de l'utilisateur sera validée avant d'être transmise au gestionnaire. Le second argument est [un sous-ensemble de l'objet `context` d'Astro](#actionapicontext).

Les valeurs de retour sont analysées à l'aide de la [bibliothèque devalue](https://github.com/Rich-Harris/devalue). Celle-ci prend en charge les valeurs JSON, ainsi que les instances de `Date()`, `Map()`, `Set()` ou `URL()`.

#### Validateur de saisie (`input`)

<p>

**Type :** `ZodType | undefined`
</p>

Une propriété facultative qui accepte un validateur Zod (par exemple, un objet Zod, une union discriminée Zod) pour valider les entrées du gestionnaire lors de l'exécution. Si la validation de l'action échoue, [une erreur `BAD_REQUEST`](#actionerror) est renvoyée et le gestionnaire (`handler`) n'est pas appelé.

Si `input` est omis, le gestionnaire (`handler`) recevra une entrée de type `unknown` pour les requêtes JSON et de type `FormData` pour les requêtes de formulaire.

#### Propriété `accept`

<p>

**Type :** `"form" | "json"`<br />
**Par défaut :** `json`
</p>

Définit le format attendu par une action :
* Utilisez `form` lorsque votre action accepte des données de formulaire (`FormData`).
* Utilisez `json`, la valeur par défaut, pour tous les autres cas.

Lorsque votre action accepte des champs de formulaire, le validateur `z.object()` analysera automatiquement `FormData` en un objet typé. Tous les validateurs Zod sont pris en charge pour valider vos champs.

<ReadMore>Découvrez comment [utiliser des validateurs avec les champs de formulaire](/fr/guides/actions/#utilisation-de-validateurs-avec-des-champs-de-formulaire) dans le guide des actions. Celui-ci comprend des exemples d'utilisation et des informations sur la gestion spéciale des champs.</ReadMore>

### `actions`

<p>

**Type :** <code>Record\<string, <a href="#actionclient">ActionClient</a>\></code>
</p>

Un objet contenant toutes vos actions avec le nom de l'action comme nom de propriété associé à une fonction pour appeler cette action.

```astro title="src/pages/index.astro" {5,8}
---
---

<script>
import { actions } from 'astro:actions';

async () => {
  const { data, error } = await actions.myAction({ /* ... */ });
}
</script>
```

Pour qu'Astro reconnaisse cette propriété, vous devrez peut-être redémarrer le serveur de développement ou [exécuter la commande `astro sync`](/fr/reference/cli-reference/#astro-sync) (`s + enter`).

### `isInputError()`

<p>

**Type :** `(error?: unknown) => boolean`
</p>

Un utilitaire utilisé pour vérifier si [une `ActionError`](#actionerror) est une erreur de validation d'entrée. Lorsque le validateur utilisé pour `input` correspond à `z.object()`, les erreurs d'entrée incluent un objet `fields` avec des messages d'erreur regroupés par nom.

<ReadMore>Consultez le [guide des erreurs de saisie de formulaire](/fr/guides/actions/#affichage-des-erreurs-de-saisie-du-formulaire) pour en savoir plus sur l'utilisation de `isInputError()`.</ReadMore>

### `isActionError()`

<p>

**Type :** `(error?: unknown) => boolean`
</p>

Un utilitaire pour vérifier si votre action a généré [une erreur `ActionError`](#actionerror) dans la [propriété du gestionnaire](#propriété-handler). Ceci est utile pour affiner le type d'une erreur générique.

```astro title="src/pages/index.astro" {9-12} "isActionError"
---
---

<script>
import { isActionError, actions } from 'astro:actions';

async () => {
  const { data, error } = await actions.myAction({ /* ... */ });
  if (isActionError(error)) {
    // Gérer les erreurs spécifiques à l'action
    console.log(error.code);
  }
}
</script>
```


### `ActionError`

Le constructeur `ActionError()` est utilisé pour créer des erreurs générées par un gestionnaire d'action (`handler`). Il accepte une propriété `code` décrivant l'erreur qui s'est produite (par exemple : `"UNAUTHORIZED"`), et une propriété facultative `message` contenant plus de détails.

L'exemple suivant crée une nouvelle erreur `ActionError` lorsque l'utilisateur n'est pas connecté :

```ts title="src/actions/index.ts" {8-11} "ActionError"
import { defineAction, ActionError } from "astro:actions";

export const server = {
  getUserOrThrow: defineAction({
    accept: 'form',
    handler: async (_, { locals }) => {
      if (locals.user?.name !== 'florian') {
        throw new ActionError({
          code: 'UNAUTHORIZED',
          message: 'Non connecté',
        });
      }
      return locals.user;
    },
  }),
}
```

Vous pouvez également utiliser `ActionError` pour affiner le type d’erreur lors de la gestion des résultats d’une action :

```astro title="src/pages/index.astro" {9-12} "ActionError"
---
---

<script>
import { ActionError, actions } from 'astro:actions';

async () => {
  const { data, error } = await actions.myAction({ /* ... */ });
  if (error instanceof ActionError) {
    // Gérer les erreurs spécifiques à l'action
    console.log(error.code);
  }
}
</script>
```

#### `code`

<p>

**Type :** <code><a href="#actionerrorcode">ActionErrorCode</a></code>
</p>

Définit une version lisible par l'homme d'un [code d'état HTTP](#actionerrorcode).

#### `message`

<p>

**Type :** `string`
</p>

Une propriété facultative pour décrire l'erreur (par exemple « L'utilisateur doit être connecté »).

#### `stack`

<p>

**Type :** `string`
</p>

Une propriété facultative pour transmettre la trace d'appels (ou « stack trace » en anglais).

### `getActionContext()`

<p>

**Type :** <code>(context: <a href="/fr/reference/api-reference/">APIContext</a>) => AstroActionContext</code><br />
<Since v="5.0.0" />
</p>

Une fonction appelée depuis votre gestionnaire middleware pour récupérer des informations sur les requêtes d'action entrantes. Elle renvoie un objet `action` contenant des informations sur la requête, une méthode `deserializeActionResult()` et les fonctions `setActionResult()` et `serializeActionResult()` pour définir par programmation la valeur renvoyée par `Astro.getActionResult()`.

`getActionContext()` vous permet d'obtenir et de définir par programmation les résultats d'actions à l'aide d'un middleware, vous permettant de conserver les résultats d'actions à partir de formulaires HTML, de bloquer les demandes d'actions avec des contrôles de sécurité supplémentaires, et bien plus encore.

```ts title="src/middleware.ts" {5}
import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';

export const onRequest = defineMiddleware(async (context, next) => {
  const { action, setActionResult, serializeActionResult } = getActionContext(context);
  if (action?.calledFrom === 'form') {
    const result = await action.handler();
    setActionResult(action.name, serializeActionResult(result));
  }
  return next();
});
```

#### `action`

<p>

**Type :** <code>\{ calledFrom: "rpc" | "form"; name: string; handler: () => Promise\<<a href="#saferesult">SafeResult</a>\>; \} | undefined</code>
</p>

Un objet contenant des informations sur une requête d'action entrante. Il est disponible via [`getActionContext()`](#getactioncontext) et fournit le nom de l'action (`name`), son gestionnaire (`handler`) et indique si l'action a été appelée à partir d'une fonction RPC côté client (par exemple `actions.newsletter()`) ou d'une action de formulaire HTML.

```ts title="src/middleware.ts" {6}
import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';

export const onRequest = defineMiddleware(async (context, next) => {
  const { action, setActionResult, serializeActionResult } = getActionContext(context);
  if (action?.calledFrom === 'rpc' && action.name.startsWith('private')) {
    // Rechercher un jeton de session valide
  }
  // ...
});
```

##### `calledFrom`

<p>

**Type :** `"rpc" | "form"`
</p>

Détermine si une action a été appelée à l'aide d'une fonction RPC ou d'une action de formulaire HTML.

##### `name`

<p>

**Type :** `string`
</p>

Le nom de l'action. Utile pour suivre la source du résultat d'une action lors d'une redirection.

##### `handler()`

<p>

**Type :** <code>() => Promise\<<a href="#saferesult">SafeResult</a>\></code>
</p>

Une méthode permettant d'appeler par programmation une action pour obtenir le résultat.

#### `setActionResult()`

<p>

**Type :** `(actionName: string, actionResult: SerializedActionResult) => void`
</p>

Une fonction permettant de définir par programmation la valeur renvoyée par `Astro.getActionResult()` dans le middleware. Le nom de l'action et un résultat d'action sérialisé par [`serializeActionResult()`](#serializeactionresult) lui sont transmis. L'appel de cette fonction depuis le middleware désactivera la gestion des résultats d'action d'Astro.

Ceci est utile lors de l'appel d'actions à partir d'un formulaire HTML pour conserver et charger les résultats d'une session.

```ts title="src/middleware.ts" {8}
import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';
export const onRequest = defineMiddleware(async (context, next) => {
  const { action, setActionResult, serializeActionResult } = getActionContext(context);
  if (action?.calledFrom === 'form') {
    const result = await action.handler();
    // ... gérer le résultat de l'action
    setActionResult(action.name, serializeActionResult(result));
  }
  return next();
});
```

<ReadMore>Consultez le [guide des sessions avancées](/fr/guides/actions/#avancé-persistance-des-résultats-daction-avec-une-session) pour un exemple d'implémentation à l'aide de Netlify Blob.</ReadMore>

#### `serializeActionResult()`

<p>

**Type :** <code>(res: <a href="#saferesult">SafeResult</a>) => SerializedActionResult</code>
</p>

Sérialise le résultat d'une action au format JSON pour la persistance. Cela est nécessaire pour gérer correctement les valeurs de retour non JSON telles que `Map` ou `Date`, ainsi que l'objet `ActionError`.

Appelez cette fonction lors de la sérialisation d'un résultat d'action à transmettre à `setActionResult()` :

```ts title="src/middleware.ts" {8}
import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';

export const onRequest = defineMiddleware(async (context, next) => {
  const { action, setActionResult, serializeActionResult } = getActionContext(context);
  if (action) {
    const result = await action.handler();
    setActionResult(action.name, serializeActionResult(result));
  }
  // ...
});
```

#### `deserializeActionResult()`

<p>

**Type :** <code>(res: SerializedActionResult) => <a href="#saferesult">SafeResult</a></code>
</p>

Inverse l'effet de [`serializeActionResult()`](#serializeactionresult) et rétablit le résultat d'une action à son état d'origine. Ceci est utile pour accéder aux objets `data` et `error` d'un résultat d'action sérialisé.

### `getActionPath()`

<p>

**Type :** <code>(action: <a href="#actionclient">ActionClient</a>) => string</code>
<Since v="5.1.0" />
</p>

Un utilitaire qui accepte une action et renvoie un chemin d'URL afin que vous puissiez exécuter un appel d'action en tant qu'opération `fetch()` directement. Cela vous permet de fournir des détails tels que des en-têtes personnalisés lorsque vous appelez votre action. Ensuite, vous pouvez [gérer les données renvoyées au format personnalisé](/fr/guides/actions/#gestion-des-données-renvoyées) selon vos besoins, comme si vous aviez appelé une action directement.

Cet exemple montre comment appeler une action `like` définie en passant l'en-tête `Authorization` et l'option [`keepalive`](https://developer.mozilla.org/en-US/docs/Web/API/Request/keepalive) :

```astro title="src/components/my-component.astro" {8,11}
<script>
import { actions, getActionPath } from 'astro:actions'

await fetch(getActionPath(actions.like), {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_TOKEN'
  },
  body: JSON.stringify({ id: 'YOUR_ID' }),
  keepalive: true
})
</script>
```

Cet exemple montre comment appeler la même action `like` en utilisant l'API [`sendBeacon`](https://developer.mozilla.org/fr/docs/Web/API/Navigator/sendBeacon) :

```astro title="src/components/my-component.astro" {5} "sendBeacon"
<script>
import { actions, getActionPath } from 'astro:actions'

navigator.sendBeacon(
  getActionPath(actions.like),
  new Blob([JSON.stringify({ id: 'YOUR_ID' })], {
    type: 'application/json'
  })
)
</script>
```

### `ACTION_QUERY_PARAMS`

<p>

**Type :** `{ actionName: string, actionPayload: string }`
</p>

Un objet contenant les noms des paramètres de requête utilisés en interne par Astro lors de la gestion des soumissions d'actions de formulaire.

Lorsque vous soumettez un formulaire via une action, les paramètres de requête suivants sont ajoutés à l'URL pour suivre l'appel de l'action :
* `actionName` - Le paramètre de requête contenant le nom de l'action appelée
* `actionPayload` - Le paramètre de requête contenant les données sérialisées du formulaire

Cette constante peut être utile lorsque vous devez nettoyer les URL après la soumission d'un formulaire. Par exemple, vous pourriez vouloir supprimer des paramètres de requête liés à une action lors d'une redirection :

```ts title="src/pages/api/contact.ts" "ACTION_QUERY_PARAMS"
import type { APIRoute } from "astro";
import { ACTION_QUERY_PARAMS } from 'astro:actions'

export const GET: APIRoute = ({ params, request }) => {
  const link = request.url.searchParams;
  link.delete(ACTION_QUERY_PARAMS.actionName);
  link.delete(ACTION_QUERY_PARAMS.actionPayload);

  return redirect(link, 303);
};
```

## Types d'`astro:actions`

```ts
import type {
  ActionAPIContext,
  ActionClient,
  ActionErrorCode,
  ActionInputSchema,
  ActionReturnType,
  SafeResult,
 } from 'astro:actions';
```

### `ActionAPIContext`

Un sous-ensemble de l'[objet de contexte Astro](/fr/reference/api-reference/). Les propriétés suivantes ne sont pas disponibles : `callAction`, `getActionResult`, `props` et `redirect`.

### `ActionClient`

<p>

**Types :**
* <code>(input?: any) => Promise\<<a href="#saferesult">SafeResult</a>\></code>
* `{ queryString?: string; orThrow: (input?: any) => Promise<Awaited<TOutput>>; }`
</p>

Représente une action à exécuter sur le client. Vous pouvez l'utiliser comme une fonction qui accepte les données d'entrée et renvoie une promesse avec un [objet `SafeResult`](#saferesult) contenant le résultat de l'action ou les erreurs de validation.

L'exemple suivant montre comment vous pouvez fournir une gestion des erreurs avec une instruction `if` lorsque l'incrémentation du nombre de mentions « J'aime » échoue :

```astro title="src/pages/articles/article-1.astro" "data" "error"
---
---

<!-- votre modèle -->

<script>
import { actions } from 'astro:actions';

const post = document.querySelector('article');
const button = document.querySelector('button');
button?.addEventListener('click', async () => {
  const { data: updatedLikes, error } = await actions.likePost({ postId: post?.id });
  if (error) {
    /* gérer les erreurs */
  }
})
</script>
```

À la place, vous pouvez l'utiliser comme un objet vous donnant accès à `queryString` et à une méthode alternative `orThrow()`.

#### Propriété `queryString`

<p>

**Type :** `string`
</p>

Une chaîne de caractères représentant l'action, permettant de créer des URL d'action de formulaire. Ceci peut être utile lorsque votre composant de formulaire est utilisé à plusieurs endroits, mais que vous devez rediriger vers une URL différente lors de l'envoi.

L'exemple suivant utilise `queryString` pour créer une URL qui sera transmise à l'attribut `action` du formulaire via une propriété personnalisée :

```astro title="src/pages/postal-service.astro" "queryString"
---
import { actions } from 'astro:actions';
import FeedbackForm from "../components/FeedbackForm.astro";

const feedbackUrl = new URL('/feedback', Astro.url);
feedbackUrl.search = actions.myAction.queryString;
---
<FeedbackForm sendTo={feedbackUrl.pathname} />
```

#### Propriété `orThrow()`

<p>

**Type :** `(input?: any) => Promise<Awaited<TOutput>>`
</p>

Une méthode qui génère une erreur en cas d'échec au lieu de renvoyer les erreurs. Ceci est utile lorsque vous souhaitez des exceptions plutôt qu'une gestion manuelle des erreurs.

L'exemple suivant utilise `orThrow()` pour ignorer la gestion des erreurs lorsque l'incrémentation du nombre de mentions « J'aime » échoue :

```astro title="src/pages/articles/article-1.astro" "orThrow"
---
---

<!-- votre modèle -->

<script>
import { actions } from 'astro:actions';

const post = document.querySelector('article');
const button = document.querySelector('button');
button?.addEventListener('click', async () => {
  const updatedLikes = await actions.likePost.orThrow({ postId: post?.id });
})
</script>
```

### `ActionErrorCode`

<p>

**Type :** `string`
</p>

Un type d'union de codes d'état HTTP standard [définis par l'IANA](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) utilisant les versions lisibles par l'homme sous forme de chaînes de caractères en majuscules séparées par un trait de soulignement (par exemple `BAD_REQUEST` ou `PAYLOAD_TOO_LARGE`).

### `ActionInputSchema`

<p>

**Type :** `ZodType`
<Since v="5.16.0" />
</p>

Un type utilitaire qui infère automatiquement le type TypeScript de l'entrée d'une action à partir de son schéma Zod. Cela peut être utile pour faire référence au [type du validateur de saisie (`input`)](#validateur-de-saisie-input) d'une action en tant qu'objet dans vos propres définitions de type.

Renvoie `never` lorsque [le validateur de saisie (`input`)](#validateur-de-saisie-input) est omis.

L'exemple suivant utilise `ActionInputSchema` avec une action nommée `contact` pour :
* Récupérer le type du schéma Zod pour l'entrée de l'action.
* Récupérer le type d'entrée attendu du validateur de l'action.

```astro title="src/components/Form.astro" {5}
---
import { actions, ActionInputSchema } from 'astro:actions';
import { z } from 'astro/zod';

type ContactSchema = ActionInputSchema<typeof actions.contact>;
type ContactInput = z.input<ContactSchema>;
---
```

### `ActionReturnType`

<p>

**Type :** <code>Awaited\<ReturnType\<ActionHandler\>\></code>
</p>

Un type utilitaire qui extrait le type du résultat d'[un gestionnaire d'actions](#defineaction). Cela donne accès à la fois l'objet `Promise` (si le gestionnaire est asynchrone) et le `ReturnType` pour vous donner le [type du résultat réel](#saferesult). Cela peut être utile si vous devez utiliser le type du résultat d'une action dans vos propres définitions de type.

L'exemple suivant utilise `ActionReturnType` pour récupérer le type du résultat attendu pour une action nommée `contact` :

```astro title="src/components/Form.astro" {4}
---
import { actions, ActionReturnType } from 'astro:actions';

type ContactResult = ActionReturnType<typeof actions.contact>;
---
```

### `SafeResult`

<p>

**Type :** `{ data: TOutput, error: undefined } | { data: undefined, error: ActionError }`
</p>

Représente le résultat d'un appel d'action :
* en cas de succès, `data` contient le résultat de l'action et `error` est indéfini (`undefined`).
* En cas d'échec, `error` contient une erreur [`ActionError`](#actionerror) avec des erreurs de validation ou d'exécution, et `data` est indéfini (`undefined`).
